by Will Watts
edited by Juanco Añez
Copyright © 1999 Will Watts. All rights reserved.
Later versions are © 2000-2003 The DUnit Group. All rights reserved.
This text may be distributed freely as long as it's reproduced in its entirety.
![]()
A Ttraditional Chinese translation of this document can be found
here
Introducing Unit Testing with DUnit
Archive contents
Getting started
Your first testing project
SetUp and TearDown
Test suites
Building suites step by stepRunning tests in console mode
Extensions
Third-Party Extensions
DUnit is a framework of classes designed to support the Xtreme approach to software testing. It supports Delphi 4 and later.
The idea is that, as you develop or change code, you develop appropriate verification tests at the same time, rather than postponing them to a later test phase. By keeping the tests up-to-date and re-applying them at regular intervals, it becomes easier to produce reliable code, and to be confident that alterations (and refactorings) do not break existing code. Applications become self-testing.
DUnit supplies classes that make it easy to organize and run these tests. DUnit provides two options for running the tests:
DUnit was originally inspired on the JUnit framework, designed by Kent Beck and Erich Gamma for the Java language, but the framework has already evolved into a more powerful tool, very specific to Delphi programming. The original Delphi port was done by Juanco Añez, and the framework is now maintained by the DUnit Group at SourceForge.
The DUnit distribution archive should be expanded into a directory of its own in a way so that its directory structure is preserved:
| Directory | Description | |||
|---|---|---|---|---|
| DUnit | ||||
| src | Library source | |||
| doc | Help file, home page and MPL license | |||
| images | Home page images | |||
| API | Time2Help generated API documentation | |||
| Contrib | Contributed modules. | |||
| XPGen | A tool for automatically generating test cases | |||
| tests | Test cases for the framework itself. | |||
| bin | Precompiled, standalone GUI test runner. | |||
| examples | ||||
| cmdline | Examples of how to invoke DUnit from the command line | |||
| collection | A Java-like collections implementation and its DUnit test cases | |||
| registration | Using the test case registration system | |||
| structure | Alternative ways to organize tests | |||
| diffunit | Placing test cases in their own units | |||
| sameunit | Placing test cases in the same unit as the tested code | |||
| registry | A step by step example of building a registry utility, with test cases | |||
| embeddable | Shows how to embed the GUITestRunner in another tool's forms. | |||
| (...) | ||||
| TListTest | Test cases for the Delphi Classes.TList object | |||
The src directory contains the following files:
| File | Description |
|---|---|
| TestFramework.pas | The framework itself. |
| TestExtensions.pas | Decorator classes that may be used to extend test cases. |
| GUITesting.pas | Classes for testing user interfaces (Forms and Dialogs). |
| TextTestRunner.pas | Routines to run tests in console mode. |
| GUITestRunner.pas | The graphical user interface to the framework.. |
| GUITestRunner.dfm | The GUITestRunner Form |
The framework directory contains precompiled
versions of the above framework units, as well as a Delphi .DCP package
definition file that can be used to link the library as a package (the
corresponding .BPL file is in the bin directory).
To write programs that use DUnit,
either the source code or the precompiled framework directories should be
included in your unit search path. You can do this by selecting
Tools | Environment Options | Library in the Delphi IDE, and
adding the DUnit path to
the list of paths shown. For example:
Alternatively, you can add the DUnit
path to the default project options, or to a specific project's options by
selecting Project | Options in the IDE:
Create a new application, and close the Unit1.pas
that Delphi automatically generates you without saving it. Save the new project
(in 'real life' placed in the same directory as the application that you wish to
test) giving it a name like Project1Test.dpr.
Create a new (formless) unit with File | New | Unit.
This is the file that will contain the test cases, so save it as something like
Project1TestCases. In the interface uses clause, add a reference to
TestFramework.
Declare a class TTestCaseFirst derived from
TTestCase,
and implement a single method TestFirst as shown below
(obviously this is a very diddy example to get you going). Note the
initialization section at the bottom, which registers the
TTestCaseFirst class with the DUnit
framework.
unit Project1TestCases; interface uses TestFrameWork; type TTestCaseFirst = class(TTestCase) published procedure TestFirst; end; implementation procedure TTestCaseFirst.TestFirst; begin Check(1 + 1 = 2, 'Catastrophic arithmetic failure!'); end; initialization TestFramework.RegisterTest(TTestCaseFirst.Suite); end.
The results that are to be tested are placed in calls to the
Check method. Here I am
unimaginatively confirming that 1 + 1 is 2. The
TestFramework.RegisterTest
procedure registers the given test in the frameworks test registration
system.
Now, before running the project, select the Project |
View Source menu option to open the project's source. Add
TestFrameWork
and GUITestRunner
to the uses clause. Remove the default Application code, and replace it with the
code shown below:
program Project1Test;
uses
Forms,
TestFrameWork,
GUITestRunner,
Project1TestCases in 'Project1TestCases.pas';
{$R *.RES}
begin
Application.Initialize;
GUITestRunner.RunRegisteredTests;
end.
Now try running the program. If all goes well, you should see the
DUnit GUI, complete with a
tree display showing available tests (currently only TestFirst).
Clicking the Run button runs the test. The GUI also allows you to enable
and disable parts of the test hierarchy by clicking on checkboxes, and has extra
buttons for conveniently selecting and deselecting tests, and complete branches.
To add further tests, simply create new test methods in
TTestCaseFirst. The
TTestCase.Suite class
method uses RTTI (RunTime Type Information) to find them and call them
automatically, provided the methods meet these two conditions:
published. Note that DUnit builds a separate instance of the class for each method that it finds, so test methods cannot share instance data.
To add two more tests, TestSecond and
TestThird, declare the methods like this:
TTestCaseFirst = class(TTestCase) published procedure TestFirst; procedure TestSecond; procedure TestThird; end; ... procedure TTestCaseFirst.TestSecond; begin Check(1 + 1 = 3, 'Deliberate failure'); end;
procedure TTestCaseFirst.TestThird; var i : Integer; begin i := 0; Check(1 div i = i, 'Deliberate exception'); end;
If you rerun the program, you will see that TestSecond
fails (it has small magenta box next to it), and TestThird
threw an exception (the box next to it is red). If any tests had succeeded their
boxes would have been green. Tests that are not run bear gray boxes. The list of
failed tests is reported in the pane bellow, and the details for each of them
can be seen in the bottom pane when they are clicked.
If you are running the program from within the IDE, you may find that the
program halts when you hit an exception. This is probably not the behavior that
you want while using DUnit.
You can disable breaking on exceptions using the Tools |
Debugger Options | Language Exceptions dialog, and un-checking the
"Stop on Delphi Exceptions" option.
One often needs to do some common preparation before running a group of
tests, and some tidying up afterwards. For example, when testing a class, you
might want to create an instance of that class, run some checks on it, and
finally free it. If you have a lot of tests to make, you'll end up with
repetitive code in each test method. DUnit
provides support for these situations through the
TTestCase virtual
methods SetUp
and TearDown,
which are called, respectively, before and after each test method is executed.
In Xtreme testing jargon, a prerequisite state like the one provided by these
two methods is known as a fixture.
The following example extends TTestCaseFirst to do
a couple of tests on the Delphi collection class TStringList:
interface
uses
TestFrameWork,
Classes; // needed for TStringList
type
TTestCaseFirst = class(TTestCase)
private
Fsl : TStringList;
protected
procedure SetUp; override;
procedure TearDown; override;
published
procedure TestFirst;
procedure TestSecond;
procedure TestThird;
procedure TestPopulateStringList;
procedure TestSortStringList;
end;
...
procedure TTestCaseFirst.SetUp;
begin
Fsl := TStringList.Create;
end;
procedure TTestCaseFirst.TearDown;
begin
Fsl.Free;
end;
procedure TTestCaseFirst.TestPopulateStringList;
var
i : Integer;
begin
Check(Fsl.Count = 0);
for i := 1 to 50 do // Iterate
Fsl.Add('i');
Check(Fsl.Count = 50);
end;
procedure TTestCaseFirst.TestSortStringList;
begin
Check(Fsl.Sorted = False);
Check(Fsl.Count = 0);
Fsl.Add('You');
Fsl.Add('Love');
Fsl.Add('I');
Fsl.Sorted := True;
Check(Fsl[2] = 'You');
Check(Fsl[1] = 'Love');
Check(Fsl[0] = 'I');
end;
When testing a non-trivial application, you will want to create more than one
class derived from TTestCase.
To add these as top-level nodes, you can simply register them in initialization
clauses, as was shown in the above example. Other times, you may want to give
more structure to your set of test cases. For this purpose, DUnit
supports the creation of test suites, which are tests that can contain
other tests, including other test suites (it is an application of the
Composite design pattern).
As it stands in the TTestCaseFirst test case, the
SetUp and TearDown
methods are called uselessly when the arithmetic testing methods run. The two
methods that deal with string lists would be better if separated into their own
test case. To do this, start by pulling apart TTestCaseFirst
into two classes, TTestArithmetic and
TTestStringlist:
type
TTestArithmetic = class(TTestCase)
published
procedure TestFirst;
procedure TestSecond;
procedure TestThird;
end;
TTestStringlist = class(TTestCase)
private
Fsl : TStringList;
protected
procedure SetUp; override;
procedure TearDown; override;
published
procedure TestPopulateStringList;
procedure TestSortStringList;
end;
(Of course, you should update the method implementations too).
Now, change the unit's initialization code to read as follows:
RegisterTest('Simple suite', TTestArithmetic.Suite);
RegisterTest('Simple suite', TTestStringList.Suite);
The TestFramework
unit exposes the
TTestSuite class,
the class that implements test suites, so you can create test hierarchies using
more explicit code:
The following function, UnitTests, creates a test
suite and adds the two test classes to it:
function UnitTests: ITestSuite;
var
ATestSuite: TTestSuite;
begin
ATestSuite := TTestSuite.create('Some trivial tests');
ATestSuite.addTest(TTestArithmetic.Suite);
ATestSuite.addTest(TTestStringlist.Suite);
Result := ATestSuite;
end;
Yet another way to implement the above function would be:
function UnitTests: ITestSuite;
begin
Result := TTestSuite.Create('Some trivial tests',
[
TTestArithmetic.Suite,
TTestStringlist.Suite
]);
end;
In the above example, the
TTestSuite constructor adds the tests in the passed
array to the suite.
You can register a test suite created in any of the above ways by using the same call you use to register individual test cases:
initialization
RegisterTest('Simple Test', UnitTests);
end.
When run with
GUITestRunner, you will see the new hierarchy.
Sometimes it is quite useful to be able run our test suites in a console
window, like when running them from within a Makefile. To run tests in console
mode, create a DPR file that uses
TextTestRunner
instead of
GUITestRunner, and add the compiler directive {$APPTYPE
CONSOLE} to the project file, or select
Project | Options | Linker | Generate console appliation
option in the IDE.
To run the example developed above as a console app, create Project1TestConsole.dpr as follows:
{$APPTYPE CONSOLE}
program Project1TestConsole;
uses
TestFrameWork,
TextTestRunner,
Project1TestCases in 'Project1TestCases.pas';
{$R *.RES}
begin
TextTestRunner.RunRegisteredTests;
end.
When the program is run, the output looks like this:
-- DUnit: Testing. ..F.E.. Time: 0.20 FAILURES!!! Test Results: Run: 5 Failures: 1 Errors: 1 There was 1 error: 1) TestThird: EDivByZero: Division by zero There was 1 failure: 1) TestSecond
Notice the string '..F.E..'. Here the framework has
printed out a period for each test passed successfully, an 'F' for tests that
failed, and an 'E' for tests that raised an exception.
You can make the
TextTestRunner halt the program with a non-zero exit code when
failures are encountered by passing a parameter with value
rxbHaltOnFailures,
like this:
TextTestRunner.RunRegisteredTests(rxbHaltOnFailures);
Halting with a non-zero exit code becomes very useful when running test suites from within a Makefile.
The TextExtensions unit contains classes that extend the functionality of the DUnit framework. Most of the classes use the decorator pattern, as defined in the GoF (Gang of Four) "Patterns of Software Design" book.
TRepeatedTest
allows you to repeat the decorated test a number of times. For example, to
repeat the TestFirst test case of
TTestArithmetic 10 times, you could write the following code:
uses
TestFrameWork,
TestExtensions, // needed for TRepeatedTest
Classes; // needed for TStringList
...
function UnitTests: ITest;
var
ATestArithmetic : TTestArithmetic;
begin
ATestArithmetic := TTestArithmetic.create('TestFirst');
Result := TRepeatedTest.Create(ATestArithmetic, 10);
end;
Notice the constructor for TTestArithmetic.
ATestArithmetic := TTestArithmetic.create('TestFirst');
Here I have passed in the name of the test method that is to be repeated. Naturally it must be spelled correctly, or disappointment will follow shortly thereafter.
If you wanted to test all of the TTestArithmetic
methods repeatedly you can stick them in a suite:
function UnitTests: ITest; begin Result := TRepeatedTest.Create(ATestArithmetic.Suite, 10); end;
TTestSetup
can be used when you wish to set up state exactly once for a test case class
(the SetUp and TearDown
methods are called once for each test method). For example, if you were writing
a suite of tests to exercise some database code, you might subclass
TTestSetup and use it
to open and close the database before executing the suite.
XPGen is a tool that automatically generates skeleton test cases for a given class. The tool can be found under the Contrib/XPGen directory in the DUnit distribution.
DUnitWizard is an open-sourced Delphi 5-7 plug-in for DUnit created by Paul Spain <paul at xpro dot con dot au>. The plug-in creates the skeleton code for DUnit projects and test cases, leaving you to concentrate on writing tests. If you would like to find out more or download visit http://xpro.com.au/Freeware/DUnitWizard.htm
DUnit homepage at SourceForge (https://sourceforge.net/projects/dunit/) Latest source, mailing lists, FAQs etc
Xtreme testing for Delphi programs ( http://www.suigeneris.org/juanca/writings/1999-11-29.html) Juancarlo Añez's introduction to his DUnit classes, originally published on the Borland Community website.
JUnit Test Infected: Programmers Love Writing Tests (http://www.junit.org/junit/doc/testinfected/testing.htm) A good article describing JUnit, the Java framework upon which DUnit is based.
Simple Smalltalk Testing: With Patterns (http://www.xprogramming.com/testfram.htm) Kent Beck's original paper. Hard going for non-Smalltalkers.
~o~